WARNING: This program is designed to scramble hard disks! Read the documentation before using it!
Contents
Part I
• Introduction
• Purpose
• How it Works
• Restrictions
• Future Directions
• Using Assimilator
• What Comes in the Package
• Creating a Customised Assimilator
• Creating a Source Folder
• Assimilator User and Source Folder Permissions
• Ready To Run
• Check List
• Further Configuration
• Abort Password
• Minimum Free Space and Trash Management
• Minimum Rerun Time
• Registering
• Site Licensing
•Getting More Help
• The MacLabManager Mailing list
• Fine Print
• Acknowledgements
Part II
• The Database of Deviancy
• Database Concepts
• The Key to Identify By
• Database Operations
• Adding Entries Quickly
• The Import/Export Business
• Fine Tuning
• Assimilator Log
• Labelling Your Source Folder
• Action Reference
• Customising Label Actions
• Miscellanea
• Desktop Database
• The Desktop Folder
• Blessed are the System Folders
• Special Files and Folders
• Aliases Explained
• Destination Disk Choice
• Time is Relative
• Backdoor Reference
• Assimilator Boot Floppy
• Even More Miscellanea
• Conclusion/Confusion
The Database of Deviancy
The goal of Assimilator is to make all of the Macintoshes in the lab look identical. This is a worthy goal but, as we all know, too much of the same thing can be bad. Some settings, such as the Sharing Setup Macintosh Name, must be different for each machine. This section describes the database that Assimilator uses to set machine specific parameters on each lab machine.
Database Concepts
There is database stored in each Assimilator document, application and extension. You can edit the database by opening the Assimilator with Assimilator Admin. The database comprises a number of records, with each record containing the following fields:
Identify By
This is the key field. It determines whether Assimilator should consider this record when it’s assimilating a machine. It contains either an Ethernet address, a hard disk creation date or a machine ID file.
Machine Name
This field contains whether Assimilator should set the Machine Name and, if so, the value to which it should be set. The Machine Name is normally set by the Sharing Setup control panel and stored in the System file and the Users & Groups Data File.
Owner Name
This field contains whether Assimilator should set the Owner Name and, if so, the value to which it should be set. The Owner Name is normally set by the Sharing Setup control panel and stored in the System file and the Users & Groups Data File.
Volume Name
This field contains whether Assimilator should set the name of the destination volume. There are three options here: Assimilator can preserve the existing name, set it to the name of the source folder or set it to some value held in the database.
TCP IP
This field contains whether Assimilator should set the MacTCP or OpenTransport IP number. Normally the IP number is set via the MacTCP or TCP/IP control panel and the value is stored in the appropriate preference file.
When Assimilator runs, it walks down the records in the database looking at the Identify By key field. If this field matches the machine on which Assimilator is running then it uses that database record to set the various machine specific parameters. If no records match then Assimilator does not set any machine specific parameters.
Note: Assimilator sets most of these preferences by bashing the relevant files with great violence. A number of these bashes have certain compatibility drawbacks. Firstly, setting the Machine Name requires Assimilator to hack up the Users & Groups Data File, because a copy of the machine name is held in that file and there in no sanctioned way to modify it. Secondly, setting the IP number requires directly bashing the TCP preference files because there is no sanctioned way to do it otherwise. Assimilator will be revised to fix any compatibility problems that arise from future system software. Welcome to the world of MacLab hackery!
The Key to Identify By
There are three ways to identify a machine uniquely:
Ethernet Address
Every Ethernet card (or Macintosh with built-in Ethernet) must contain a 48 bit number that identifies the card uniquely. If your Macs have Ethernet then you definitely should use the Ethernet address to identify them.
Hard Disk Date
The creation date on the destination hard disk is a common way of identifying hard disks uniquely. It works because the creation date is stores in seconds and it’s difficult to get two disks with the same creation date if you initialise them by hand.
Unfortunately if you get a big batch of machines — such as a new Mac laboratory for example — you will often find that all the hard disks have the same creation date. If you reinitialise each of the hard disks manually then the creation dates will be unique and you will be able to use them as the key.
Machine ID File
The final, and least preferred, mechanism to identify a machine is by a machine ID file. This is a file in the Preferences folder whose name uniquely identifies the machine. The file must be of type 'Asim' and creator 'Asim', with zero length data and resource forks. Assimilator ignores such files when assimilating the hard disk. You must be extra careful to make sure that your machine ID files meet these requirements, otherwise they’ll be assimilated.
Database Operations
Assimilator Admin contains all of the basic tools required to maintain the database. The Assimilator’s configuration window contains an Edit Database button, which brings up a dialog showing each of the database records. You can click the Add button to add a new database record, the Delete button to delete the selected records, the Change button to edit a single record, and the Done button to dismiss the dialog.
When you add or change a database record you encounter the Add/Edit Entry dialog, which allows you to set the fields of the record. The meaning of each of the fields is described in a previous section.
Adding Entries Quickly
The most common problem you face as a lab administrator is having a whole bunch of machines whose Identify By keys (typically their Ethernet addresses) are unknown. Fortunately, Assimilator Admin has a shortcut for adding lots of individual entries easily.
The first step is to put a copy of Assimilator Admin on a floppy disk. Now put an Assimilator document, application or extension in the same folder as the Assimilator Admin program. Now go to a lab machine and run Assimilator Admin while holding down the control key. Assimilator Admin will bring up the Quick Add Entry dialog.
This dialog has the Identify By information set up in the best way possible. If the machine has Ethernet then the key is set to the Ethernet address of the Ethernet card. If the machine does not have Ethernet then the key is set to the hard disk’s modification date but you can easily switch it to a machine ID file.
After you’ve confirmed the Identify By key field, you can simply type in the other information associated with this database record. When you click OK Assimilator Admin will automagically add this record to the database contained in the Assimilator document, application or extension in the same folder as it and then quit. You can now eject the floppy disk and take it to the next machine and repeat the operation.
Note: If you OK the dialog when the machine ID file option is set then Assimilator Admin will create the file for you.
The Import/Export Business
Because Assimilator Admin’s facilities for editing the database are rather basic, it also provides a facility to export the database to a text file and then reimport a modified database from a text file. The format of this text file is rather hard to explain. If you’re interested you should export a simple database and work it out from that.
Fine Tuning
Once you have got Assimilator working then you can spend considerable time fine tuning it for your particular installation. This section describes some of the useful mechanisms for doing this.
Assimilator Log
When Assimilator runs it creates a log of all its actions in a file called “Assimilator Log” in the Assimilator trash folder. You can look in this log for a description of the actions taken and the reasons for those actions.
Interpreting the log is the key to fine tuning Assimilator. Each line in the log starts with an action and ends with a reason. For example, imagine some has thrown away the ClarisWorks application on the hard disk. When Assimilator runs it sees that the ClarisWorks application is missing and downloads a new copy from the server. The log entry would look like:
Downloading “ClarisWorks” because it is missing.
The log actions are:
Startup
Assimilator records the date and time that it runs as the first item in the log.
Finish
Assimilator records the date and time that it finishes as the last item in the log. You can use this to calculate the time taken for assimilation.
Trashing
Assimilator is throwing away an item; the reason is given as part of the log entry.
Downloading
Assimilator is downloading an item; the reason is given as part of the log entry.
Blessing
Assimilator will automatically bless any System Folder that it downloads and record that action in the log. The exact criteria for a System Folder to be blessed is covered in a later section.
Deleting
Assimilator is deleting an item. The primary reason is given as part of the log entry. Items are only deleted if they cannot be held in the trash while maintaining the minimum disk free space requirement.
The log reasons are:
it is missing
The item is present in the source folder but missing on the destination hard disk.
one is a folder, one is a file
The item is a file on the source folder and a folder on the destination hard disk or vice versa.
moddate
The item on the destination volume has a different modification date from that in the source folder.
file type
The item on the destination volume has a different file type from that in the source folder.
file creator
The item on the destination volume has a different file creator from that in the source folder.
rsrc length
The item on the destination volume has a different resource fork length from that in the source folder. Basically this means that the file has changed size.
data length
The item on the destination volume has a different data fork length from that in the source folder. Basically this means that the file has changed size.
it is marked to always download
The item on the server has been marked as “Always Download” using a Finder label.
it is in the way of a download
The item on the destination volume is being discarded because a replacement item is being downloaded. This entry always has a matching entry that explains why the replacement item is being downloaded.
it should not be here
it should not be here (root)
The item on the destination volume is being discarding because it is not in the source folder. Don’t ask me why there are two different messages for this!
we are zarching the entire harddisk
Assimilator is zarching the entire hard disk and thus it discarding all files.
the desktop folder should be empty
There are items on the destination volume’s desktop but the desktop is supposed to be empty.
Labelling Your Source Folder
Once you have got your machines assimilating happily you should look at your log and see what actions Assimilator is taking and why. What you will find is that a number of files are being downloaded every time Assimilator runs. This is usually because the files are modified in the process of system startup. Unfortunately the most serious offender is the System file, which is also very big. So it’s worth your time to analyse the Assimilator log and see how things can be improved.
The way you stop a file being downloaded every time is to label it (using the Finder) to indicate that to Assimilator that it is to take a special action. By default the labels and there actions are:
None — Download if Modified
Essential — Always Download
Hot — Download if Different
In Progress — Download if Missing
Cool — Never Download
Personal — Download if Modified & Make Invisible
Project 1 — Always Download & Make Invisible
Project 2 — Download if Different & Make Invisible
You can change these default actions using the instructions in the next section but normally there is no need to do so.
The default action, which corresponds to no Finder label, is to download a file if it has been modified. The definition of modified, as far as Assimilator is concerned, is that either the file has changed or the modification date has changed.
In the case of the System file, the modification date changes every time the machine restarts. You can tell Assimilator to ignore this modification date by labelling the file with the Hot label, which means the file is only downloaded if it is different — where different means that the file size, type or creator has changed.
If, after you’ve labelled it Hot, the file is still being downloaded, then you can take more drastic action. If you label the file as In Progress then it will only be downloaded if it’s missing, that is the file is present on the source but not on the destination. Although this is generally not recommended for use on files it is useful for recalcitrant files whose modification date and size change at system startup. This label acts slightly differently on folders: if a folder is marked as download if missing and the folder is present on the lab machine Assimilator does not search inside that folder, it just moves on. If the folder is missing normal Assimilation occurs and the folder, along with its contents, are downloaded according to the labelling. Very useful for creating User folders.
The other labels are useful too. The Essential label tells Assimilator to always download the file every time. This is useful for files like the MacTCP DNR file, which regularly get corrupted. Because the file is small, the load from downloading it every time is minor, certainly compared to the hassle of having to deal with a corrupted one.
The final action is achieved using the Cool label, which corresponds to the never download action. Assimilator will never download an item that is labelled Cool but it will also not throw it away. One possible use for this is to create a “Users” folder, where users can store their own personal files. If you label it Cool then Assimilator will not attempt to download the folder from the source (very sensible because it would be empty on the server) and it will not discard the folder on the destination.
The remaining Finder labels (Personal, Project 1 and Project 2) and analogues of some of the other labels except that they also tell Assimilator to render the item invisible after it has downloaded it. This is useful in scenarios where you want to project the System Folder on the destination disk from casual tinkering. While you can’t make the entire System Folder invisible (the Finder gets upset) you can make the Extensions folder, System and Finder invisible. This ensures that the casual tinkerer can’t prevent a clean system restart, which in turns means that Assimilator will run and clean up the machine at that time.
Note: Assimilator will download invisible files in the source folder and render them invisible on the destination disk. The invisible labels are useful when you want the files to be visible on the server (so that you operate on them, for example installing new Fonts in the System file) but invisible on the lab machines.
One helpful hint is to change the name of the Finder labels (in the Labels control panel) to correspond with their Assimilator actions.
Action Reference
Assimilator supports the following actions:
Download Always
The item (and its contents if it’s a folder) is always downloaded. Any existing item on the destination is always trashed.
Download if Modified
If applied to a file, the file is downloaded if the one on the destination is different from the one on the server or the file’s modification date have changed.
If applied to a folder this just causes Assimilator to recursively operate to items within the folder.
Download if Different
If applied to a file, the file is downloaded if the one on the destination is different from the one on the server. The definition of different is the the file size, type or creator has changed.
If applied to a folder this just causes Assimilator to recursively operate to items within the folder.
Download if Missing
The item is downloaded if it is in the source folder but not on the destination disk. If applied to a folder Assimilator does not recursively operate on items within the folder unless the folder is missing on the destination disk. As a special case, if there is a file in the source and a folder on the destination (or vice versa) the item is considered to be missing.
Never Download
The item is never downloaded. If the item exists on the destination then it is preserved. If it doesn’t exist on the destination then nothing happens. If there’s a file on one and a folder on the other then still nothing happens.
Any of these actions can be combined with the invisible action, which forces the item to be invisible on the destination disk.
Customising Label Actions
There are 5 basic Assimilator actions:
Download if Modified
Always Download
Download if Different
Download if Missing
Never Download
There is also one modifier, the invisible checkbox, which determines whether an item is to be made invisible after it has been downloaded. This yields 10 (2 times 5) combinations. Eight of these combinations are associated with the eight Finder labels. By default the associations are:
None — Download if Modified
Essential — Always Download
Hot — Download if Different
In Progress — Download if Missing
Cool — Never Download
Personal — Download if Modified & Make Invisible
Project 1 — Always Download & Make Invisible
Project 2 — Download if Different & Make Invisible
You can change these associations using the popup menus and checkboxes in the Label Actions panel of the Assimilator’s configuration window. Normally the default associations are correct and you don’t need to change anything.
Miscellanea
This section contains a whole pile of hints and tips that didn’t fit anywhere else (–:
Desktop Database
In order to support double clicking documents, the Macintosh maintains a list of applications are available in something called the desktop database. When it downloads or trashes an application (technically anything with a bundle), Assimilator attempts to update the desktop database. Normally this works fine and you do not need to worry about it but in certain circumstances it may be necessary to rebuild the desktop database completely. You can do this by holding down the command and option keys while the Finder starts up (usually at the end of the startup time).
The Desktop Folder
Under System 7, items that are “on the desktop” are actually held in a special, invisible folder called “Desktop Folder” that lurks at the root of each hard disk. You would think that they way to achieve this is to create a “Desktop Folder” inside the source folder and put the items you want on the lab machine’s desktops in that folder. Unfortunately it’s not that easy!
Firstly, the Finder won’t let you create a folder called “Desktop Folder” because the name is “reserved by the system software”. This is fairly easy to workaround. If you create a folder called “•Desktop Folder•” (immediately inside the source folder) then Assimilator will treat it as if it’s the desktop folder.
Secondly, it’s quite hard to get the icons to appear in the right position on the desktop. There are a number of problems with this, not all of which are well understood. The best solution is to follow the advice given earlier in this document, whereby you create the source folder by dragging the entire hard disk of a prototype lab machine up to the file server. This will create a “Desktop Folder”, including all of the icons in the right position. You should then modify that folder carefully, making sure to always keep it in the big Icon view.
Blessed are the System Folders
The Macintosh keeps track of the currently active System Folder on each disk because it needs that information at startup time. For historical reasons this folder is known as the “blessed folder” and the act of setting this folder is known as “blessing a folder”. Blessing the wrong folder will prevent the Macintosh from starting. In order to guarantee that the correct folder is blessed, Assimilator will bless any folder that contains a System file. It recognises the System file by its file type 'zsys' and creator 'MACS'. You should make sure that you only have one System file in your source folder and that it is the correct System Folder.
Assimilator adds a log entry whenever it blesses a folder. If you have blessing problems you should consult the log to find out what went wrong.
Special Files and Folders
Because Assimilator is fully System 7 aware it knows about, and deals correctly with, a number of special files that are maintained by System 7. These are documented here for completeness:
AppleShare PDS
Move&Rename
Network Trash Folder
These file and folders are found in the root directory of the hard disk and used by file sharing.
Desktop DB
Desktop DF
Desktop
These files are kept in the root directory of the hard disk and make up the desktop database.
Trash
This folder holds the items that are in the trash.
Shutdown Check
This file is created by the System 7.5 General Controls control panel shut down warning check.
VM Storage
This file is used by the System 7 VM system.
Aliases Explained
Assimilator attempts to correct any aliases that it downloads from the source folder. This process is a little tricky and it deserves an explanation. When it downloads an alias from the source folder, Assimilator resolves the alias. If the alias points to some item within the source folder then Assimilator corrects the alias so that it now points to the corresponding item on the destination hard disk. This is usually the Right Thing™.
For example, lets say your source folder is called “Source Folder” and is held on a volume called “Source Volume” and you have an alias “Source Volume:Source Folder:•Desktop Folder•:SimpleText alias” that points to the application inside source folder, that is “Source Volume:Source Folder:Applications:SimpleText”. Assimilator will download the alias to “Dest Disk:Desktop Folder:SimpleText alias” and the application to “Dest Disk:Applications:SimpleText”. If Assimilator took no other action than the alias on the desktop folder of the destination disk would still point to the source folder and not to the copy of SimpleText on the hard disk. This is obviously the Wrong Thing™. Instead Assimilator corrects the alias so that it points to “Dest Disk:Applications:SimpleText”.
Whenever Assimilator fixes an alias, it adds a log entry describing its actions. In fact, it’s a bit verbose in reporting it’s actions, so it will list all the aliases it looks at and will show “errors” for the ones it decides not to fix (for example, aliases pointing to somewhere outside the source folder). The rule here is “don’t be alarmed” :-)
Destination Disk Choice
Each time Assimilator runs, it’s faced with the choice of which disk to assimilate. Surprisingly enough, it’s actually quite hard to determine this. Assimilator uses the following algorithm: it assimilates the first disk that is larger than 2MB (this eliminates floppy disks), is not hardware locked (which eliminates CD ROMs) and is not an AppleShare volume (which means it won’t try to assimilate your file server). You can use this algorithm to your advantage when building an Assimilator floppy, as described in a later section.
Time is Relative
It’s important to remember that Assimilator uses the modification date of files to determine whether they’ve changed. If the times on your server, you administration machine and your lab clients are different then Assimilator may erroneously conclude that files have been modified even whether they haven’t. I recommend that you install a time synchronisation utility to ensure that the time is the same on all of your machines. Time synchronisation programs include LocalTime (freeware), Network Time (shareware), LabMaster (shareware) and KeyServer (commercial).
Backdoor Reference
Assimilator has a surprising number of backdoors, that is special key combinations that cause it to perform some special operation.
control key while launching Assimilator
If you hold down the control key while launching Assimilator, it will ignore the minimum rerun time run immediately. This is described better in the section “Minimum Rerun Time”.
control and shift keys while launching Assimilator
If you hold down the control key and shift keys while launching Assimilator, it will ‘zarch the destination disk’. This process involves throwing away all existing files on the disk and downloading all new copies from the source folder. Zarch does not delete the desktop database files or any of the other special files. Zarch is the best way to completely rebuild a suspect Macintosh.
control key while launching Assimilator Admin
If you hold down the control key while launching Assimilator Admin, it will display the Quick Add Entry dialog. This is described better in the section “Adding Entries Quickly”.
Assimilator Boot Floppy
It is possible to build a single floppy disk that will boot any currently available machine and assimilate it. This task has been greatly simplified by the System 7.5 Network Access Disk that was recently released by Apple. At the time of writing, a disk image for this is available from:
There are two approaches you can take but both of them start with the Network Access Disk. The first approach merely requires you to boot the machine from the network access floppy, put it on the correct network using the Network control panel on that disk, then log into the file server using AppleShare (also on that disk) and run Assimilator from the file server.
The second approach is more automated but it’s also more work to set up. First you start with a network access floppy. You then throw away the Finder on that disk, which frees up considerable disk space. Then take a copy of your customised Assimilator application and change its file type to 'FNDR' and its creator to 'MACS'. Rename it to “Finder” and put it in the System Folder of the network access floppy. Assimilator will now automatically run when you boot a machine from that disk. Because of the destination disk algorithm (discussed in an earlier section) it will chose to assimilate the machine’s hard disk and not the floppy.
Note: If your machine is on Ethernet then it’s possible that the above procedure won’t work because the machine has accidentally reverted to LocalTalk. You can get around this either by using the previous procedure or by including a PRAM zapping extension on the boot disk. Such a utility is available as:
Assimilator waits for a few seconds at the beginning of each assimilation to give you time to abort it without damage. This is vitally important if you accidentally try to assimilate a non-lab Macintosh.
Force Quit
Assimilate disables System 7’s Force Quit key combination (command-option-escape) while it is running.
Progress Bar
It is impossible to provide a decent progress bar for Assimilator without doubling the time it takes to assimilate. Please stop asking for one!
You Need More Power???
Assimilator, would you believe, is designed to greatly simplify the process of maintaining laboratory Macintoshes. To do this, I have avoided adding a number of features that could conceivably be useful for you. If you need more power for your Mac lab, try out RevRdist by Dale Talcott <aeh@cc.purdue.edu>. It’s freeware (as opposed to Assimilator, which you are expected to pay for) and has tonnes of power (more power than I could ever hope to deal with). It is on the UMich archives in util/network/.
Conclusion/Confusion
It is very easy to get confused when trying to set up Assimilator. The whole issue of maintaining Macintosh laboratories is rather complicated and Assimilator is a merely one step on the path to a solution, not the entire solution.
Assimilator is the product of years of experience running Mac labs and it works well if you set it up correctly. When you’re confronted by problems please take the time to read this manual carefully. It contains a wide array of hints and tips for setting up your lab.
